This is Matrix.
Matrix is an open source project that publishes the
Matrix open standard
reference implementations
Maintained by the non-profit Matrix.org Foundation, we aim
to create an open platform which is as independent, vibrant and evolving as the Web itself... but for communication.
As of June 2019, Matrix is out of beta, and the protocol is fully suitable for production usage.
If you share our vision, or are building on top of Matrix, please consider donating...
Support us on Patreon for great rewards including access to the supporters-only podcast, and even a voice at our weekly meetings.
Find out more at our Patreon page
You can also send us cryptocurrency:
BTC 1LxowEgsquZ3UPZ68wHf8v2MDZw82dVmAE
ETH 0xA5f9a4f9E024F6D727f7afdA9257e22329A97485
DOT 12JDhAt3Y1NPpcLMxunH2f8DASZemC6nWPC9nkXdT3ui4zJG
If you share our vision, or are building on top of Matrix, please consider donating. See our current Elliptic supporters!
Matrix gives you simple HTTP APIs and SDKs (iOS, Android, Web) to create chatrooms, direct chats and chat bots, complete with end-to-end encryption, file transfer, synchronised conversation history, formatted messages, read receipts and more.
Conversations are replicated over all the servers participating in them, meaning there are no single point of control or failure. You can reach any other user in the global Matrix ecosystem of over 40M users, even including those on other networks via bridges.
Matrix provides state-of-the-art end-to-end-encryption via the Olm and Megolm cryptographic ratchets. This ensures that only the intended recipients can ever decrypt your messages, while warning if any unexpected devices are added to the conversation.
Matrix’s encryption is based on the Double Ratchet Algorithm popularised by Signal, but extended to support encryption to rooms containing thousands of devices. Olm and Megolm are specified as an open standard and implementations are released under the Apache license, independently audited by NCC Group.
With the advent of WebRTC, developers gained the ability to exchange high quality voice and video calls – but no standard way to actually route the calls.
Matrix is the missing signalling layer for WebRTC. If you are building VoIP into your app, or want to expose your existing VoIP app to a wider audience, building on Matrix’s SDKs and bridges should be a no-brainer.
Matrix owes its name to its ability to bridge existing platforms into a global open matrix of communication. Bridges are core to Matrix and designed to be as easy to write as possible, with Matrix providing the highest common denominator language to link the networks together.
The core Matrix team maintains bridges to Slack, IRC, XMPP and Gitter, and meanwhile the wider Matrix community provides bridges for Telegram, Discord, WhatsApp, Facebook, Signal and many more.
Matrix can handle any type of real-time data, not only messaging and VoIP.
By building bridges to as many IoT silos as possible, data can be securely published on the Matrix network. IoT solutions built on Matrix are unified, rather than locked to specific vendors, and can even publish or consume Matrix data directly from devices via ultra-low bandwidth transports (100bps or less)
Meanwhile AR and VR vendors are recreating the silos we’ve seen in instant messaging rather than working together towards an open ecosystem. Matrix can be the unifying layer for both communication and world data in AR and VR.
Matrix is really a decentralised conversation store rather than a messaging protocol. When you send a message in Matrix, it is replicated over all the servers whose users are participating in a given conversation - similarly to how commits are replicated between Git repositories. There is no single point of control or failure in a Matrix conversation which spans multiple servers: the act of communication with someone elsewhere in Matrix shares ownership of the conversation equally with them. Even if your server goes offline, the conversation can continue uninterrupted elsewhere until it returns.
This means that every server has total self-sovereignty over its users data - and anyone can choose or run their own server and participate in the wider Matrix network. This is how Matrix democratises control over communication.
By default, Matrix uses simple HTTPS+JSON APIs as its baseline transport, but also embraces more sophisticated transports such as WebSockets or ultra-low-bandwidth Matrix via CoAP+Noise.
curl -XPOST
-d '{"msgtype":"m.text", "body":"hello"}'
"https://matrix.alice.com/_matrix/client
/v2/rooms/ROOM_ID/send/m.room.message
?access_token=ACCESS_TOKEN"
{
"event_id": "$YUwRidLecu:alice.com"
}
curl –XPOST –H 'Authorization: X-Matrix origin=alice.com,...' –d '{
"ts": 1413414391521,
"origin": "alice.com",
"destination": "bob.com",
"pdus": [{
"event_id": "$YUwRidLecu:alice.com",
"content": {
"body": "hello world",
"msgtype": "m.text"
},
...
"pdu_type": "m.room.message",
"signatures": {
"matrix.org": {
"ed25519:auto": "jZXTwAH/7EZ..."
}
},
"sender": "@alice:alice.com"
}]
}' https://matrix.bob.com:8448/_matrix/federation/v1/send/916d...
curl "https://matrix.bob.com/_matrix/client
/v2/sync?access_token=ACCESS_TOKEN"
{
"next_batch": "s72595_4483_1934",
"rooms": [{
"room_id": "!KrLWMLDnZAyTapqLWW:alice.com",
"events": {
"batch": [{
"event_id": "$YUwRidLecu:alice.com",
"type": "m.room.message",
"content": {
"body": "I am a fish",
"msgtype": "m.text",
},
"origin_server_ts": 1417731086797,
"sender": "@alice:alice.com"
}],
},
}]
}
Hey all, Matrix 1.6 is out there! Like Matrix 1.5 back in November , this release is largely a maintenance update. Matrix 1.1 through 1.…
Matrix Live Dept of Spec 📜 Andrew Morgan (anoa) says MSC Status New MSCs: MSC3964: Notifications for room tags MSCs in Final Comment…
For the past two years, FOSDEM couldn’t happen in-person. Fortunately we could
help, and Matrix hosted the world's largest free & open…
Matrix Live No Matrix Live today, but there will be a lot of Matrix content this weekend at
FOSDEM in the Matrix
devroom , and Matthew's…
Join thousands of other developers in our open source repositories, including:
Synapse
JavaScript SDK
Android SDK
iOS SDK
Matrix is managed through an open governance process, looked after by The Matrix.org Foundation - a non-profit UK Community Interest Company.
It acts as a neutral guardian of the Matrix spec, nurturing and growing Matrix for the benefit of the whole ecosystem.
The Guardians are the legal directors of the Foundation, responsible for ensuring that it keeps on mission and neutrally protects the development of Matrix.
Matrix.org is generously hosted by UpCloud! Host your homeserver via UpCloud and get a $25 credit.
To connect to the Matrix federation, you will use a client. These are some of the most popular Matrix clients available today, and more are available at try-matrix-now. To get started using Matrix, pick a client and join #matrix:matrix.org. To see more clients in a features matrix, see the Clients Matrix.


















An important idea in Matrix is Interoperability. This means that Matrix is open to exchanging data and messages with other platforms using an Open Standard. We refer to the connection to other platforms as bridging.
For a thorough examination of the different methods of bridging, and a discussion of the terminology involved, check out How do I bridge thee? Let me count the ways...
Portal rooms: these control chunks of room aliases namespace. For example, #freenode_#channelname:matrix.org corresponds to #channelname on Freenode. In this way, Matrix users can transparently join IRC channels on Freenode. Portal rooms are typically managed by the remote network's side of the room.
Plumbed rooms: these rooms are "plumbed" into one or more specific remote rooms by configuring a bridge (which can be run by anyone). For instance, #matrix:matrix.org is plumbed into #matrix on Freenode, matrixdotorg/#matrix on Slack, etc. Access control for Matrix users is necessarily managed by the Matrix side of the room. This is useful for using Matrix to link together different communities.
Bridgebot-style: in this case, messages in either direction are conveyed by a bot residing on the given platform. This is a sub-optimal experience because metadata is lost. For example, all messages might be sent by the same bot, but with the message text prefixed with the name of the original sender.
Puppeting: solves the problems of Bot-based bridging by "puppeting", meaning controlling, a user on the other side of the bridge. This means that to native users, they see messages as being sent from the correct sender. Double-puppeting means this is done in both directions of the bridge. This is the most preferred way of implementing a Matrix bridge.







An application service gateway from Matrix.org for bridging between IRC networks and Matrix, written using matrix-appservice-node. You can get the code on GitHub.
Supports dynamically bridging IRC channels on demand, synchronised user-lists, and other goodness.

A bouncer-style Matrix IRC bridge with focus on simplicity for personal use on your own homeserver. No complex configuration files or databases required.
This project bridges Slack to Matrix.
The bridge allows you to connect Matrix rooms and Slack channels together. It supports bridging via webhooks or via a
dedicated slack integration (using the Events API). The bridge supports nearly all matrix message types and client features
with active development on new features as they arrive. Check the list below for feature support.
The bridge is regularly hacked on and is accepting new PRs for bugfixes and features, come and get involved!
✓ Direct (1:1) Chats
✓ Group (‘Channel’) Chats
✗ History
✓ Typing notifications and read receipts
✓ Text Messages
✓ Reactions
✓ Redactions/Deleting Events
✓ Threading/Replies
✓ Formatted Text Content
✓ Media Content
When using Element with the default integrations manager (scalar.vector.im), you can enable the Slack integration per-room. Click the "Room info" button in the top right corner of the page and then click "Add widgets, bridges & bots".
Get it from GitHub!
A Matrix-Slack puppeting bridge. Written in Go using a fork of slack-go
✓ 1:1 and group DMs
✓ Channels
✓ Slack connect channels
✓ Plain text and formatted messages
✓ Threads
✓ Message redaction/deletion
✓ Reactions
✗ Custom emojis (Slack -> Matrix only)
✓ Own read status sync
✓ Double puppeting
✗ Backfilling history
✗ Relaybot mode
✓ End-to-bridge encryption
mx-puppet-slack bridges slack and matrix together via (double)puppeting. Additionally a relay mode can be enabled.
✓ Direct (1:1) Chats
✓ Group ('Channel') Chats
✓ Plain Text
✓ Formatted Messages
✓ Media/files
✓ Redactions/Deletions
✓ Presence (Slack → Matrix only)
✓ Typing notifications (Slack → Matrix only)
✓ Replies
✓ Edits
✓ Reactions
✓ Stickers
✓ Multi-user
✓ Multi-team
✓ Initiate chats from matrix
✗ History
This bridge is part of the mx-puppet-bridge suite of puppeting bridges.
mx-puppet-discord bridges discord slack and matrix together via (double)puppeting. Additionally, a relay mode can be enabled.
✓ Direct (1:1) Chats
✓ DM Group Chats
✓ Plain Text
✓ Formatted Messages
✓ Media/files
✓ Redactions/Deletions
✓ Presence (both ways)
✓ Typing notifications (both ways)
✓ Replies
✓ Edits
✓ Reactions
✓ Stickers
✓ Multi-user
✓ Friends management
✓ Initiate chats from matrix
✗ History
✗ Threads
This bridge is part of the mx-puppet-bridge suite of puppeting bridges.
A Matrix-Discord puppeting bridge. Written in Go using a fork of discordgo
✓ 1:1 and group DMs
✓ Text channels
✗ Forum channels
✓ Automatic space creation for guilds and guild channel categories
✓ Plain text and formatted messages
✓ Replies
✓ Threads
✓ Message redaction/deletion
✓ Reactions
✓ Custom emojis (Discord -> Matrix only)
✓ Own read status sync
✓ Double puppeting
✗ Backfilling history
✓ Login by scanning QR or providing token
✗ Relaybot mode
✓ End-to-bridge encryption
This project bridges Discord to Matrix via the Application API.
✓ Plain Text
✓ Formatted Messages
✓ Media/files
✓ Redactions/Deletions
✓ Presence (Discord → Matrix only)
✓ Typing notifications (Discord → Matrix only)
✓ Replies
✓ Stickers
✓ Puppeting ( Can configure to puppet via a script)
✗ Group/1:1 Chats
✗ Calls
You can self host matrix-appservice-discord in order to bridge your rooms
from Discord, it is also available from t2bot.io at https://t2bot.io/discord.
A simple bridge between Matrix and Discord.
✓ Plain Text
✓ Discord emojis bridged as inline images
✓ Files
✓ Redactions/Deletions
✓ Typing notifications
✓ Replies
✓ Puppeting (Optional Appservice on Matrix, webhooks on Discord)
✗ Group/1:1 Chats
A Matrix-Google Chat puppeting bridge. Written in Python using a fork of hangups and mautrix-python.
✓ 1:1 chats
✓ Group chats
✓ Plain text
✓ Threads
✓ Formatted messages
✓ Images
✗ Voice messages
✓ Other file types
✓ Typing notifications and read receipts
✓ Double puppeting
✓ Backfilling history and missed messages
✓ End-to-bridge encryption
A Matrix-QQ puppeting bridge based on MiraiGo and mautrix-go.
✓ Private chat
✓ Group chat
✓ Plain text message
✓ Most message media (photo, video, voice, file, location)
✓ Reply and mention
✓ Double puppeting
Current feature list at https://github.com/duo/matrix-qq#features--roadmap
matrix-tencent-forward-bot (mtfb) is a forward bot between Matrix and Tencent QQ.
A Matrix-Wechat puppeting bridge based on mautrix-go.
✓ Private chat
✓ Group chat
✓ Plain text message
✓ Most message media (photo, video, voice, file, location)
✓ Reply and mention
✓ Double puppeting
Current feature list at https://github.com/duo/matrix-wechat#features--roadmap
matrix-appservice-wechaty is a new project to bridge Matrix with WeChat.

A Matrix-WhatsApp puppeting bridge. Written in Go using whatsmeow
✓ 1:1 chats
✓ Group chats
✓ Status updates
✓ Plain text and formatted messages
✓ Message redaction/deletion
✓ Most message media (photos, videos, voice messages, documents, locations, contacts)
✓ Replies and mentions
✓ Presence, read receipts and typing notifications
✓ Double puppeting
✓ Backfilling history and missed messages
✓ End-to-bridge encryption

A Matrix-Twilio relaybot bridge for WhatsApp Business. Can also be used for Twilio SMS bridging with small modifications. Written in Python using mautrix-python.
✓ 1:1 chats
✗ Group chats
✓ Plain text and formatted messages
✓ Images, videos and files
A LinkedIn Messaging <-> Matrix puppeting bridge. Written in Python using linkedin-messaging-api and mautrix-python.
✓ 1:1 chats
✓ Group chats
✗ User Profiles, Companies or anything else outside the LinkedIn Messaging functionality
✓ Plain text messages (rich text is not supported by LinkedIn)
✓ Most message media (photos, videos, GIFs, files)
✓ Mentions
✓ Message redaction/delete
✓ Double puppeting
✓ Backfilling history and missed messages
✓ End-to-bridge encryption
Connect to RSS and Twitter feeds via Ryan Rix's feedbot!
Check it out from Ryan's git repo

Bridges between a Murmur server and a Matrix channel.
ICE is used to communicate with the Murmur server, matrix-nio is used for Matrix.
✓ Bridges text messages bidirectional
✗ 1:1 chats
✓ Bridge connect / disconnect notifies to Matrix
✓ Bridges images from Matrix to Mumble
✗ Bridges images from Mumble to Matrix
✓ Configurable selection of which Murmur channels to be bridged.
✓ Easy to add message handlers to filter or modify messages before bridging.

A simple Matrix to Mumble (Murmur) bridge using gRPC. Currently, it bridges one channel in Matrix to a server in Murmur.
✗ Direct Chats
✓ Presence (using messages)
✓ Formatted Text Content
✓ Image Content
✗ Calls
A simple Android SMS (text message) <--> Matrix bridge. With this bridge you can get all your text messages on Matrix and reply to them.
Get it and report issues at github, or install from F-Droid.
An Android app that wraps mautrix-imessage
to bridge SMS from your Android phone to Matrix.
Setup instructions on docs.mau.fi.
✓ SMS (text messages)
✓ MMS (photos and other attachments)
✗ RCS
✓ Group chats
✓ Backfilling messages from Android SMS database
✓ Double puppeting (for backfilling)
✓ End-to-bridge encryption
A Matrix puppeting bridge, which allows you to bridge matrix rooms to SMS with one outgoing telephone number only. It is build on top of matrix-spring-boot-sdk and written in Kotlin.
This is a library for bridging matrix and skype,api lib used go-skypeapi.
✓ Create group/private conversation
✓ Group conversations
✓ Private conversation
✓ Group conversations
✓ Kick/invite/leave/join(group)
✓ Generate invitation link(group)
✓ Quote message(Circular references may have some bugs)
✓ Mention someone(message)
✓ delete message
✓ Media message
✓ Picture message
✓ Group avatar/name change
✓ User name/avatar change
This is a Matrix bridge for Skype. It uses skype-http under the hood.

A matrix-bridge written in Golang to let you read and write your emails in matrix. You can have multiple email accounts in different private rooms.
An application service gateway for bridging between Email and Matrix, written using Spring Boot (Java) using matrix-java-sdk.
You can get the code on github.
Features:
This repo contains (almost) transparent matrix gateway.
Following features are implemented:
+-----------+ +-----------+
| | +---------------+ | |
| >===AS=API====> >===SMTP===> |
| Matrix HS | | Matrix-email | | Email |
| <===Client/===< Bridge <===LMTP===< Server |
| | AS API | | | |
| | +-------A-------+ | |
| | | | |
+-----------+ | +-----------+
+----V----+
|Bridge DB|
| (SQL) |
+---------+This is a puppeted Facebook bridge for Matrix.
Get it from GitHub.
A Matrix-Facebook Messenger puppeting bridge. Written in Python using maufbapi and mautrix-python.
✓ 1:1 chats
✓ Group chats
✗ Pages, Facebook groups or anything else outside Messenger
✓ Plain text and formatted messages
✓ Most message media (photos, videos, voice messages, files, locations)
✓ Replies and mentions
✓ Message redaction/unsend
✓ Read receipts
✓ Double puppeting
✓ Backfilling history and missed messages
✓ End-to-bridge encryption

This is a Matrix bridge for Apple iMessage. It connects your homeserver to Messages.app
Find the source on GitHub.

A Matrix-iMessage puppeting bridge.
✓ iMessage and SMS chats
✓ Photos and other attachments
✓ Replies (iMessage->Matrix only)
✓ Tapbacks (iMessage->Matrix only)
✓ Double puppeting
✓ Backfilling missed messages
✓ End-to-bridge encryption
A Matrix-KakaoTalk puppeting bridge based on mautrix-python that uses node-kakao as its backend.
✓ 1:1 chats
✓ Group chats
✓ Text messages
✓ Most message media (images, videos, voice messages, files)
✗ Stickers
✗ Message reactions
✗ Open Profiles
✗ Voice calls
✓ Replies and mentions
✓ Message redaction/unsend
✓ Read receipts
✓ Double puppeting
✓ Backfilling history and missed messages
✓ End-to-bridge encryption

This project bridges Mattermost to Matrix. Supported
features:
✓ Formatted messages
✓ Join/leave
✓ Attachments
✓ Username Substitutions
✓ Edits
✓ Replies
✓ Redaction
✓ Typing notification Mattermost -> Matrix)
✗ Direct messages
✗ Presence
✗ Reactions

General purpose puppeting bridges using libpurple and other backends.
This bridge is in very active development currently and intended mainly for experimentation and evaluation purposes.
The project has been discontinued.
A bridge that connects a user's Keybase account to their Matrix account.
This is a Matrix bridge for GroupMe.
You will need to acquire your Access Token from GroupMe.
Get your access token by going to https://dev.groupme.com/ and clicking the "Access Token" link in the top right.
mx-puppet-groupme is a puppeting GroupMe bridge.
✓ DMs
✓ Group chats
✓ Plain text
✓ Formatted messages
✓ Media/files
✓ Typing notifications
✓ Read receipts (DMs only)
✓ Replies
✓ Likes (reactions)
✓ Multi-user
✓ Initiate DMs from Matrix
✗ Initiate group chats from Matrix
✗ History
This bridge is part of the mx-puppet-bridge suite of puppeting bridges.
A Matrix-LINE puppeting bridge based on running LINE's Chrome extension in Puppeteer.
Fork of mautrix-amp.
✓ 1:1 chats
✓ Group chats
✗ Voice calls
✗ LINE Keep, LINE News, LINE Clova, or anything else outside the Messenger App
✓ Read receipts
✓ Double puppeting
✓ Backfilling history and missed messages
✓ End-to-bridge encryption
A Matrix-Instagram DM puppeting bridge. Written in Python using mauigpapi and mautrix-python.
✓ 1:1 chats
✓ Group chats
✗ Stories
✗ Feed
✓ Plain text
✗ Formatted messages
✓ Message reactions
✓ Message redactions
✓ Photos, videos and gifs
✗ Arbitrary files
✓ Typing notifications and read receipts
✗ Presence
✓ Double puppeting
✓ Backfilling history and missed messages
✓ End-to-bridge encryption
A Matrix-Signal puppeting bridge. Written in Python using mautrix-python.
Communicates with Signal using signald.
✓ 1:1 chats
✓ Group chats
✓ Plain text
✗ Formatted messages
✓ Photos, gifs, voice notes and other files
✓ Stickers (only Signal->Matrix)
✓ Read receipts
✓ Typing notifications (only Signal->Matrix)
✓ Double puppeting
✓ End-to-bridge encryption
A Matrix-Telegram hybrid puppeting/relaybot bridge. Written in Python using Telethon and mautrix-python.
✓ Private chats, groups, supergroups and channels
✗ Secret chats
✓ Plain text and formatted messages
✓ Most message media (photos, videos, voice messages, documents, locations, stickers, polls, dice rolls)
✓ Replies and mentions
✓ Message redaction/deletion
✓ Typing notifications and read receipts
✓ Double puppeting
✓ Backfilling history and missed messages
✓ End-to-bridge encryption
...and much more. Read the current feature list at https://github.com/mautrix/telegram.
A Matrix-Twitter DM puppeting bridge. Written in Python using mautwitdm and mautrix-python.
✓ 1:1 chats
✓ Group chats
✗ Tweets
✓ Plain text
✗ Formatted messages
✓ Photos, videos and gifs
✓ Double puppeting
✓ Backfilling history and missed messages
✓ End-to-bridge encryption
mx-puppet-twitter bridges twitter and matrix together via (double)puppeting.
✓ Direct (1:1) Chats
✗ Tweets
✓ Plain Text
✗ Formatted Messages
✓ Media/files
This bridge is part of the mx-puppet-bridge suite of puppeting bridges.
mx-puppet-tox bridges tox and matrix together via (double)puppeting. It basically acts as a tox client for matrix.
✓ Direct (1:1) Chats
✗ Group Chats
✓ Plain Text
✗ Formatted Messages (unsupported by tox)
✓ Media/files
✓ Presence (Tox → Matrix only)
✓ Typing notifications (Tox → Matrix only)
✓ Multi-user
This bridge is part of the mx-puppet-bridge suite of puppeting bridges.
A Matrix<->Mastodon bot written in Java.
This project bridges Gitter to Matrix and is already hosted for you. It creates portal rooms for every public room on Gitter which you can join via #org_repo:gitter.im (just replace the / in the Gitter URI with an underscore _). For example https://gitter.im/nodejs/node corresponds to #nodejs_node:gitter.im.
If you're already using Element, you can browse all of the Gitter rooms in the public room directory (switch to the gitter.im server).
✓ Public Chats
✗ Private Chats
✓ 1:1 Chats
✓ Native feeling usernames/avatar on both sides (virtual users)
✓ Replies/Threaded conversations
✓ Formatted Messages
✓ Mentions
✓ Edits
✓ Redactions/Deletions
✓ Status /me messages
✓ Media/Files
✗ Reactions
✗ Backfilling history
✗ Read Receipts
✗ Typing notifications
If you're curious about the bridge, there is a great overview of the capabilities and future plans in this Matrix.org blog post.
How to get started with Matrix
Guides to usage of Matrix
Installing Synapse, a homeserver implementation written in Python
How to develop for Matrix
Matrix FAQ
How to manage and moderate Matrix rooms
The Matrix Specification
Find a Matrix Client for you
Bridge to platforms outside Matrix
Find a comprehensive list of Matrix-related projects
| If you want to… | Then read… |
|---|---|
| Just get started! | Getting Involved, which explains various ways of getting started with Matrix or the FAQ |
| Get started with the CS API using … | |
| … JavaScript | Usage of the matrix-js-sdk |
| … Python | Matrix Python SDK documentation |
| Understand Application Services | The Application services guide introduces them and explains what they can be used for |
| See an example of a simple bot | tiny-matrix-bot source code |
| Create a complete working chatbot | Using Matrix to make Chatbot software from the 1960s available in 2018 goes from the basics, brings in matrix-bot-sdk, and ends with deployment on a Raspberry Pi |
| Work on Bridges to Matrix | Types of Bridging should be read by all bridge developers to ensure everyone has the same mental map of terminology when implementing bridges |
| Migrate from the old v1 CS API | the v1 migration guide which justs lists the changes from v1 to r0 |
| Use E2E in a client application | The End-to-end Encryption Implementation Guide is intended for client developers who wish to add support for end-to-end encryption to their clients |
| Install Synapse | Installing Synapse Guide |
| … using Docker | the Synapse Docker README |
| Understand Moderation in Matrix | Moderation in Matrix |
| Article | Author | Language |
|---|---|---|
| Guide to matrix.org and riot.im | Michael Snoyman | English |
| Riot Matrix from La Foresta | La Foresta team | Italian |
| IRC for the 21st Century: Introducing Riot | Justin W. Flory | English |
| Introduction à Matrix et guide d'utilisation | Adrien Luxey | French |
| Werde Teil der Matrix | Samuel | German |
To install Synapse, we recommend taking a look at the Installing Synapse guide page. Other articles are listed below.
| Article | Author | Language |
|---|---|---|
| Compressing Synapse database | Victor Berger / Levans | English |
| How to monitor Synapse metrics using Prometheus | Synapse Team | English |
| Using Postgres | Synapse Team | English |
| How to enable VoIP relaying on your Home Server with TURN | Synapse Team | English |
| Setting up Federation | Synapse Team | English |
| Use of Server Notices | Synapse Team | English |
| Use of OpenTracing | Synapse Team | English |
| Scaling synapse via workers | Synapse Team | English |
| Boosting matrix/synapse by using workers | Mark Nowiasz | English |
| Article | Author | Language |
|---|---|---|
| An introduction to end-to-end encryption in Matrix and Riot | Hubert Chathi | English |
| Article | Author | Language |
|---|---|---|
| How to translate Riot-Web | Riot-Web Team | English |
| Article | Author | Language |
|---|---|---|
| Matrix Bridging to IRC, Slack and Telegram | Jon Spriggs | English |
| Riot - Messagerie Instantanée Décentralisée & Sécurisée ! | Nouts | French |
| Article | Author | Language |
|---|---|---|
| Types of Bridging | Matrix.org | English |
| Bridging Matrix with WhatsApp running on a VM | Matrix.org | English |
| Article | Author | Language |
|---|---|---|
| Usage of the matrix-js-sdk | Matrix.org | English |
| Migrating from Client Server API v1 | Matrix.org | English |
| Client Server API | Matrix.org | English |
| Using Matrix to make Chatbot software from the 1960s available in 2018 | Matrix.org | English |
| Client Developers' Guide to Supporting SSO | Matrix.org | English |
| Creating a simple read-only Matrix client | Matrix.org | English |
| Usage of matrix-bot-sdk | Matrix.org | English |
| matrix-bot-sdk Room Admin Features | Matrix.org | English |
| Usage of matrix-nio (Python Matrix client library) | Matrix.org | English |
| Article | Author | Language |
|---|---|---|
| End-to-End Encryption implementation guide | Matrix.org | English |
| Implementing more advanced e2ee features, such as cross-signing | Sorunome | English |
| An introduction to end-to-end encryption in Matrix and Riot | Hubert Chathi | English |
| Article | Author | Language |
|---|---|---|
| State Resolution v2 for the Hopelessly Unmathematical | Neil Alexander Twigg | English |
| Article | Author | Language |
|---|---|---|
| Introduction | Matrix.org | English |
| How can I get involved? | Matrix.org | English |
| Moderation in Matrix | Matrix.org | English |
| Application Services | Matrix.org | English |
| Made for Matrix Badge Guidelines | Matrix.org | English |
| The Matrix Jobs Room | Matrix.org | English |
| Running online events with Open Source communication tools | Matrix.org | English |
| Enter the Matrix | Brendan Abolivier | English |
| Obtain Access Tokens from Element | TravisR | English |
| Testing the matrix.org client-server API using cURL | Rick Cogley | English |
| Article | Author | Language |
|---|---|---|
| Installing Synapse | Matrix.org | English |
| Self-hosting a map tile server for location sharing | Andy Balaam | English |
| Free Matrix Server using Oracle Cloud | Paul Tötterman <paul.totterman@iki.fi> | English |
| Understanding Synapse Hosting | Matrix.org | English |
Matrix is an open standard for interoperable, decentralised, real-time communication over IP. It can be used to power Instant Messaging, VoIP/WebRTC signalling, Internet of Things communication - or anywhere you need a standard HTTP API for publishing and subscribing to data whilst tracking the conversation history.
Matrix defines the standard, and provides open source reference implementations of Matrix-compatible Servers, Client SDKs and Application Services to help you create new communication solutions or extend the capabilities and reach of existing ones.
Client
Users in Matrix use one or more clients to communicate. This could be any combination of a web client, a command line client, a mobile client - or embedded clients built into existing apps. It could even be a piece of hardware (e.g. a drone) that is Matrix enabled.
client SDK
A client SDK makes it easier to develop client applications using matrix. See: How do I Matrix-enable my existing app?
Matrix’s initial goal is to fix the problem of fragmented IP communications: letting users message and call each other without having to care what app the other user is on - making it as easy as sending an email.
The longer term goal is for Matrix to act as a generic HTTP messaging and data synchronisation system for the whole web - allowing people, services and devices to easily communicate with each other, empowering users to own and control their data and select the services and vendors they want to use.
The aim is to provide an analogous ecosystem to email - one where you can communicate with pretty much anyone, without caring what app or server they are using, using whichever client app & server you chose, and use a neutral identity system like an e-mail address or phone number to discover people to talk to.
Client
Users in Matrix use one or more clients to communicate. This could be any combination of a web client, a command line client, a mobile client - or embedded clients built into existing apps. It could even be a piece of hardware (e.g. a drone) that is Matrix enabled.
We are called Matrix because we provide a structure in which all communication can be matrixed together.
No, it’s nothing to do with the film (although you could go and build virtual worlds on top of Matrix if you wanted 😎).
matrixed together
In mathematics, a matrix is a lattice-like arrangement, in which expressions can be combined and treated as a single entity
You can find the full list of Matrix enabled projects at https://matrix.org/blog/try-matrix-now.
client SDK
A client SDK makes it easier to develop client applications using matrix. See: How do I Matrix-enable my existing app?
The Matrix.org Foundation is a non-profit UK Community Interest Company, incorporated to act as the neutral guardian of the standard on behalf of the whole Matrix community. It is an open initiative which acts as a neutral and independent custodian of the Matrix standard.
The Foundation defines the manifesto, mission and values of the project, the open governance process that determines how the specification develops, and provides a safety-net to ensure the project stays independent and true to its goals.
Matrix.org is currently funded by the community, through a
combination of community support (via
Patreon,
Liberapay, Bitcoin and Ethereum),
corporate sponsorship, and grant funding.
Current Elliptic-level supporters on
Patreon and corporate sponsors can be found on our supporters
page.
If you would like to support the core Matrix team as a member of the community, you can do so via:
If you would like to sponsor the
team as a corporation, or are interested in paying for prioritised or custom
development, please get in touch.
For the first three years of Matrix's development (2014-2017), most of the core
contributors worked for Amdocs, who paid for them to
work fulltime on Matrix. In July 2017, Amdocs considered the project to be
sufficiently successful that it could now self-support and so stopped funding.
The majority of the core team is now employed by Element, an independent company
set up to hire the team and support Matrix's development. Other contributors
are funded by their own employers or donate their own time to the project.
The core team is ~12 people with extensive experience in building custom VoIP and Messaging apps for mobile network operators. Most of us work for Element, but there are an increasing number of contributors from other companies and folks all over the internet.
We believe that any open standard defining interoperable communication needs to be justified, demonstrated and validated with transparent open source implementations. For Matrix to achieve its mission of making all communications services interoperable we believe it needs to be truly open, giving people access to take all the code we produce and to use and build on top of it.
interoperable
A more general definition of interoperability is for systems to be able to freely exchange data with another by a known mechanism. In the case of matrix, we have openly documented how to communicate with our HTTP APIs.
Matrix is an open standard, meaning that we have freely published the details for how to communicate interoperably using the Matrix set of HTTP APIs. We encourage anyone and everyone to use the APIs and build their own projects which implement them and so benefit from interoperability with the rest of the Matrix ecosystem. We also ensure the standard is not encumbered by any known patent licensing requirements.
Matrix is also open source, meaning that we have released the source code of the reference servers, clients and services to the public domain under the Apache Licence v2, to encourage anyone and everyone to run their own servers and clients, and enhance them and contribute their enhancements as they see fit.
interoperable
A more general definition of interoperability is for systems to be able to freely exchange data with another by a known mechanism. In the case of matrix, we have openly documented how to communicate with our HTTP APIs.
Federation allows separate deployments of a communication service to communicate with each other - for instance a mail server run by Google federates with a mail server run by Microsoft when you send email from @gmail.com to @hotmail.com.
interoperable clients may simply be running on the same deployment - whereas in federation the deployments themselves are exchanging data in a compatible manner.
Matrix provides open federation - meaning that anyone on the internet can join into the Matrix ecosystem by deploying their own server.
federation
Federation means that separate instances of a service communicate - the best example of this is email servers, in which it's possible to send mail between difference service providers. For Matrix, this means that data about rooms and message history is shared between servers of participating users.
interoperable
A more general definition of interoperability is for systems to be able to freely exchange data with another by a known mechanism. In the case of matrix, we have openly documented how to communicate with our HTTP APIs.
The History of email is instructive when thinking about the importance of interoperability.
Early email systems behaved as isolated communities which only allowed you to exchange mail with users on the same system. If you got your email from one service and your friend from another, then you couldn't message each other. This is basically the situation we're in today with VoIP and IM.
interoperable
A more general definition of interoperability is for systems to be able to freely exchange data with another by a known mechanism. In the case of matrix, we have openly documented how to communicate with our HTTP APIs.
There have been several attempts before including RCS.
All of these have had some level of success, but many different technological/usability/economic factors have ended up limiting their success. Unfortunately, we've not ended up in a world where everyone has a SIP URI or Jabber ID on their business card, or a phone that actually uses RCS.
Take a look at the Comparisons section for a more detailed look at how Matrix compares to other projects.
SIP
Session Initiation Protocol is a communications protocol for signaling and controlling multimedia communication sessions in applications of Internet telephony for voice and video calls.
XMPP
XMPP is a communication protocol for message-oriented middleware based on XML. We think of Matrix and XMPP as being quite different; at its core Matrix can be thought of as an eventually consistent global JSON database, whilst XMPP can be thought of as a message passing protocol.
RCS
Rich Communication Services is a communication protocol between mobile-telephone carriers and between phone and carrier, aiming at replacing SMS messages with a text-message system that is richer, provides phonebook polling (for service discovery), and transmit in-call multimedia.
A typical client provides a simple chatroom interface to Matrix - letting the user interact with users and rooms anywhere within the Matrix federation. Text and image messages are supported, as well as voice and video calling via WebRTC in one-to-one rooms and via Jitsi elsewhere.
Client
Users in Matrix use one or more clients to communicate. This could be any combination of a web client, a command line client, a mobile client - or embedded clients built into existing apps. It could even be a piece of hardware (e.g. a drone) that is Matrix enabled.
federation
Federation means that separate instances of a service communicate - the best example of this is email servers, in which it's possible to send mail between difference service providers. For Matrix, this means that data about rooms and message history is shared between servers of participating users.
There are plenty of ways to get involved. First, create a user account and come say hi on #matrix:matrix.org!
Then...
See CONTRIBUTING.md for full details on how to contribute to the project. All are welcome!
Synapse
Synapse is a homeserver implemented in Python by the matrix.org core team. It is currently by far the most installed homeserver available.
the spec
The Matrix Specification describes the interactions between actors in the Matrix ecosystem, including Server-Server and Client-Server. You can see the spec here.
Client
Users in Matrix use one or more clients to communicate. This could be any combination of a web client, a command line client, a mobile client - or embedded clients built into existing apps. It could even be a piece of hardware (e.g. a drone) that is Matrix enabled.
bridging
Bridging to Matrix means that it's possible to read and write to channels hosted outside matrix. For example, it's possible to speak in IRC and slack rooms.
The point of entry for everything matrix is #matrix:matrix.org aka #matrix on irc.libera.chat.
If you're a developer and are looking to get involved with building something on Matrix, try #matrix-dev:matrix.org.
If you host a Synapse homeserver, you can get support in the #synapse:matrix.org room.
room
A room is a fundamental building bock of the matrix architecture: events are typically sent in the context of a room. A room is a conceptual place where users can send and receive events. Events are sent to a room, and all participants in that room with sufficient access will receive the event. See more detail.
Synapse
Synapse is a homeserver implemented in Python by the matrix.org core team. It is currently by far the most installed homeserver available.
You can link to a Matrix room or user by going to matrix.to, and typing in the room alias or ID for linking to rooms, or a user's Matrix ID for linking to users. In the future, there will be a URL scheme for Matrix rooms and users, similar to email's mailto scheme, or XMPP's xmpp scheme.
See also the following lists: Clients, Clients Matrix, and Which matrix clients support E2E?
There are many clients available, ranging from the glossy mass-market to the geeky command-line. There's even an emacs macro.
The most popular and established client is Element, available on web, desktop, Android and iOS.
Alternatively you can find a client suitable for you:
A thorough list of clients can be found on the try-matrix-now page.
There are a large number of 'bridges' which integrate existing communication networks into Matrix. This list is growing rapidly, and you can find bridges both written by the Matrix core team and contributed by the wider community. The full list can be seen at https://matrix.org/bridges/
As of July 2018, active bridges include:
Writing new bridges is incredibly fun and easy - see the matrix-appservice-bridge HOWTOfor an example of how to write a fully functional Slack bridge in less than 100 lines of code!
bridging
Bridging to Matrix means that it's possible to read and write to channels hosted outside matrix. For example, it's possible to speak in IRC and slack rooms.
The quickest way is to pick a client and sign up.
Clients can access any homeserver—you don't have to use matrix.org, though historically it is the largest public homeserver. anchel.nl lists free public homeservers, and a few other resources for getting started.
homeserver
Each account in the Matrix federation is associated with a single homeserver. The software running at this server stores the history and account information for that user. Homeservers synchronise message history with other homeservers.
Element is available for Android and iOS.
The iOS version can be downloaded from the Apple store.
The Android version can be downloaded from the Google Play store or F-Droid. If you are not sure which one to choose, install Element from the Google Play store.
Element
Element is a popular matrix client developed by the core matrix.org team. It's available as a web app, on Android and on iOS.
The F-Droid release of Element does not use Google Cloud Messaging. This allows users that do not have or want Google Services installed to use Element.
The drawback is that Element has to pull for new messages, which can drain your battery. To counter this, you can change the delay between polls in the settings. Higher delay means better battery life (but may delay receiving messages). You can also disable the background sync entirely (which means that you won't get any notifications at all).
If you don't mind using Google Services, you might be better off installing the Google Play store version.
See also: What clients are available?
You can use Element Web - a glossy web client written on top of matrix-react-sdk.
You can also host Element on your own server. It's a static web application, just download the last release and unpack it.
neo is a Matrix React.js webclient which aims to be lighter than Element while still feature complete.
See also: What clients are available?
You can use the desktop build of Element Web.
There are also other desktop clients - check the list of clients on matrix.org.
If you're using Element, you can use
the "Explore" screen, which you open from a
button next to the search box on the right.
It you're working on a client, you can use the Client-Server API to
get a list of public rooms.
'Server Notices' are a new feature introduced in Synapse 0.30. They provide a channel whereby server administrators can send messages to users on the server.
Read more about them in the Synapse docs on Server Notices and in the Server Notices section of the Matrix Client-Server Spec.
If your app doesn't have any communication capability already, you'll want to use one of the Matrix client SDKs to add it in. These come in different levels of sophistication - ranging from a simple HTTP API wrapper through to reusable UI components.
There are even more client SDKs available.
Pick the one for your platform, or a 3rd party one if none of the above work for you, and get plugging it in. You'll probably also want to read the Client-Server API HOWTO too.
If you already have communication infrastructure set up (XMPP, custom HTTP, or whatever), then you'll want to run a bridge to expose it to the wider Matrix ecosystem. See matrix-appservice-bridge HOWTO for a guide of how to write bridges using the matrix-appservice-bridge framework, or co-opt one from the list at https://matrix.org/blog/try-matrix-now.Application Service API gives the details of the API that bridges have to implement.
client SDK
A client SDK makes it easier to develop client applications using matrix. See: How do I Matrix-enable my existing app?
See the Client-Server API HOWTO and the API docs and the Spec for all the details you need to write a client.
"Enter the Matrix" from Brendan Abolivier is a great introductory article which also covers the CS API.
We're not yet managing a registry of custom matrix event types. If you have any particularly good ones you want to tell the world about, please let us know on #matrix-dev:matrix.org.
Yes. Matrix is just a spec, and implementations of the spec are very welcome!
Synapse is the most well-distributed homeserver, but other projects aiming to implement the server component include:
the spec
The Matrix Specification describes the interactions between actors in the Matrix ecosystem, including Server-Server and Client-Server. You can see the spec here.
homeserver
Each account in the Matrix federation is associated with a single homeserver. The software running at this server stores the history and account information for that user. Homeservers synchronise message history with other homeservers.
Synapse
Synapse is a homeserver implemented in Python by the matrix.org core team. It is currently by far the most installed homeserver available.
bot
A bot is an autonomous agent. In the context of matrix, it means software which is able to make automated posts in rooms.
Client
Users in Matrix use one or more clients to communicate. This could be any combination of a web client, a command line client, a mobile client - or embedded clients built into existing apps. It could even be a piece of hardware (e.g. a drone) that is Matrix enabled.
HTTP may not be the most efficient transport, but it is ubiquitous, very well understood and has numerous implementations on almost every platform and language. It also has a simple upgrade path to HTTP/2, which is relatively bandwidth and round-trip efficient.
For these reasons it has been chosen as the mandatory baseline of the exchange, but it is still entirely possible to use other protocols for communication between clients and server (see for example this websocket transport spec proposal), and it's also possible in the future that negotiation of more efficient protocols will be added for the federation between servers, with HTTP+JSON remaining as the compatibility baseline.
federation
Federation means that separate instances of a service communicate - the best example of this is email servers, in which it's possible to send mail between difference service providers. For Matrix, this means that data about rooms and message history is shared between servers of participating users.
You can choose a client and create a user account on an existing homeserver.
To host your own, start by looking at recommended guides for installing Synapse.
homeserver
Each account in the Matrix federation is associated with a single homeserver. The software running at this server stores the history and account information for that user. Homeservers synchronise message history with other homeservers.
federation
Federation means that separate instances of a service communicate - the best example of this is email servers, in which it's possible to send mail between difference service providers. For Matrix, this means that data about rooms and message history is shared between servers of participating users.
Synapse
Synapse is a homeserver implemented in Python by the matrix.org core team. It is currently by far the most installed homeserver available.
Follow these instructions to install Synapse.
homeserver
Each account in the Matrix federation is associated with a single homeserver. The software running at this server stores the history and account information for that user. Homeservers synchronise message history with other homeservers.
Synapse
Synapse is a homeserver implemented in Python by the matrix.org core team. It is currently by far the most installed homeserver available.
We recommend servers use port 8448 for server<->server HTTPS traffic. Look at "Setting up Federation" in the Synapse docs for details.
Client<->Server traffic can talk directly to Synapse via port 8448, but as by default Synapse creates a self-signed TLS certificate this can cause problems for clients which can't easily trust self-signed certificates (e.g. most web browsers). Instead, you can proxy access to Synapse's HTTP listener on port 8008 via an existing HTTPS proxy with a valid certificate (e.g. an nginx listening on port 443), or you can point Synapse at a valid X.509 signed TLS certificate. In future, Synapse will probably use letsencrypt to autogenerate valid certificates rather than self-signed ones during installation, simplifying this process enormously.
You can also put Synapse entirely behind an existing TLS load balancer and not expose port 8448 at all. In this situation, Synapse will need to be configured to share the same public TLS certificate as the load balancer (as Synapse uses the public certificate for identity in other areas too, and it has to match the certificate that other servers see when they connect).
If you have a successfully running Synapse instance and want to federate with the rest of the public network, take a look at the federation documentation.
federation
Federation means that separate instances of a service communicate - the best example of this is email servers, in which it's possible to send mail between difference service providers. For Matrix, this means that data about rooms and message history is shared between servers of participating users.
See also: What is an identity server?
Yes - the reference implementation is sydent and you can run your own ID server cluster that tracks 3rd party to Matrix ID mappings. This won't be very useful right now, though, and we don't recommend it.
If you want your server to participate in the global replicated Matrix ID service then please get in touch with us. Meanwhile, we are looking at ways of decentralising the 'official' Matrix identity service so that identity servers are 100% decentralised and can openly federate with each other. N.B. that you can use Matrix without ever using the identity service - it exists only to map 3rd party IDs (e.g. email addresses) to matrix IDs to aid user discovery.
Currently, the homeserver name is assumed never to change. This means that if you rename your server, other servers will think it's a different server.
Perhaps in the future we will add an API for changing the homeserver name, but for now this is not supported.
homeserver
Each account in the Matrix federation is associated with a single homeserver. The software running at this server stores the history and account information for that user. Homeservers synchronise message history with other homeservers.
There are several approaches to bot creation (and you'll find even more on the SDKs page.)
We firmly believe it is what is right for the consumer. As people begin to use interoperable communications tools, service providers will see the benefit and compete on quality of service, security and features rather than relying on locking people into their walled garden. We believe as soon as users see the availability and benefits of interoperable services they will demand it.
interoperable
A more general definition of interoperability is for systems to be able to freely exchange data with another by a known mechanism. In the case of matrix, we have openly documented how to communicate with our HTTP APIs.
We do recognise the advantages of working with existing standards bodies. We have been focused on writing code and getting it out, and the standard has been evolving rapidly since initial release in September 2014. Once the standard has matured sufficiently it may well be appropriate to work with an official standard body to maintain it going forwards.
A very quick recap by-the-numbers (updated May 2020):
As of September 2019, the Matrix ecosystem has dozens of independent homeserver hosts, many bridges and is under active development.
See also: What do you mean by open?
The Apache Licence is a permissive licence. We want the Matrix protocol itself to be free and open, but people are free to create both free and commercial apps and services that uses the protocol. In our opinion, any Matrix-service only enhances the Matrix ecosystem.
We love IRC. In fact, prior to the point where Element was stable enough for daily use IRC was our primary communication tool. Between us we've written IRCds, IRC bots and admined dreamforge, UnrealIRCd, epona, ircservices and several others. That said, it has some limitations that Matrix seeks to improve on:
IRCv3 exists and is addressing some of these issues; this is great news and we wish them well. It's almost a contradiction in terms to get competitive between openly interoperable communication projects - in fact there there already exist mature Matrix<->IRC bridges. matrix-appservice-irc is currently used to bridge with Libera.Chat and many other IRC networks.
Element
Element is a popular matrix client developed by the core matrix.org team. It's available as a web app, on Android and on iOS.
federation
Federation means that separate instances of a service communicate - the best example of this is email servers, in which it's possible to send mail between difference service providers. For Matrix, this means that data about rooms and message history is shared between servers of participating users.
We think of Matrix and XMPP as being quite different; at its core Matrix can be thought of as an eventually consistent global JSON database with an HTTP API and pubsub semantics - whilst XMPP can be thought of as a message passing protocol. You can use them both to build chat systems; you can use them both to build pubsub systems; each comes with different tradeoffs. Matrix has a deliberately extensive 'kitchen sink' baseline of functionality; XMPP has a deliberately minimal baseline set of functionality. If XMPP does what you need it to do, then we're genuinely happy for you! Meanwhile, rather than competing, an XMPP Bridge like Skaverat's xmpptrix beta or jfred's matrix-xmpp-bridge or Matrix.org's own purple-matrix has potential to let both environments coexist and make the most of each other's benefits.
The whole area of XMPP vs Matrix is quite subjective. Rather than fighting over which open interoperable communication standard works the best, we should just collaborate and bridge everything together. The more federation and interoperability the better.
XMPP
XMPP is a communication protocol for message-oriented middleware based on XML. We think of Matrix and XMPP as being quite different; at its core Matrix can be thought of as an eventually consistent global JSON db, whilst XMPP can be thought of as a message passing protocol.
pubsub
The publish-subscribe pattern describes an architecture in which message senders push messages to a location, without needing to know who the subscribers will be. For Matrix, this means a client can send a message to a room without knowing the members, and the members can read that message.
Trillian and Pidgin and similar aggregating IM clients merge all your IM activity into a single app. However, your history and identity is still fragmented across the networks. People can't find you easily, and your history is fragmented (other than on the device where the client runs). And rather than being able to chose the right app for the job when communicating with people, you are pushed towards relying on a specific aggregation app.
Matrix lets you get the best of both worlds by linking to all the different networks (XMPP, AIM, ICQ, Lync, Skype etc) on the serverside, using bridges which can be run by anyone. Matrix then provides a simple standard HTTP API to access any of these networks, and lets you choose whichever client you prefer (either as a 'native' Matrix client or using a non-Matrix client from one of the networks which has been bridged in).
Users in Matrix use one or more clients to communicate. This could be any combination of a web client, a command line client, a mobile client - or embedded clients built into existing apps. It could even be a piece of hardware (e.g. a drone) that is Matrix enabled.
Yes! An ever increasing number of protocols are being bridged into Matrix, so if you use something like IRC on Libera.Chat you may well be indirectly benefiting from Matrix, as others may be connected into the IRC channel via Matrix.
bridging
Bridging to Matrix means that it's possible to read and write to channels hosted outside matrix. For example, it's possible to speak in IRC and slack rooms.
A user's client connects to a single homeserver, which stores the communication history and account information for that user, and shares data with the wider Matrix ecosystem by synchronising communication history with other homeservers.
Client
Users in Matrix use one or more clients to communicate. This could be any combination of a web client, a command line client, a mobile client - or embedded clients built into existing apps. It could even be a piece of hardware (e.g. a drone) that is Matrix enabled.
Matrix user IDs (MXID) are unique user IDs. They are in the format @username:homeserver.tld (this format is used to avoid confusing them with email addresses.) They are intended to be fairly hidden (although right now they are not) - instead you will find and identify other users via 3PIDs.
3PID
Third-party IDs (3PIDs) are IDs from other systems or contexts, such as email addresses, social network accounts and phone numbers.
Third-party IDs (3PIDs) are IDs from other systems or contexts, such as email addresses, social network accounts and phone numbers.
Users in Matrix are identified internally via their 3PID namespaces such as email addresses or phone numbers should be used publicly to identify Matrix users, at least for invitation purposes. A Matrix "Identity" describes both the user ID and any other existing IDs from third party namespaces linked to their account.
Matrix users can link third-party IDs (3PIDs) to their user ID. Linking 3PIDs creates a mapping from a 3PID to a user ID. This mapping can then be used by Matrix users in order to discover the MXIDs of their contacts.
In order to ensure that the mapping from 3PID to user ID is genuine, the intention is for a globally federated cluster of trusted "Identity Servers" (IS) be used to verify the 3PID and persist and replicate the mappings. Usage of an IS is not required in order for a client application to be part of the Matrix ecosystem. However, without one clients will not be able to look up user IDs using 3PIDs.
The precise architecture of identity servers is currently in flux and subject to change as we work to fully decentralise them.
MXID
Matrix user IDs (MXID) are unique user IDs. They are in the format @username:homeserver.tld.
3PID
Third-party IDs (3PIDs) are IDs from other systems or contexts, such as email addresses, social network accounts and phone numbers.
Each replicated across all of the homeservers whose users are participating in a given room.
homeserver
Each account in the Matrix federation is associated with a single homeserver. The software running at this server stores the history and account information for that user. Homeservers synchronise message history with other homeservers.
Client
Users in Matrix use one or more clients to communicate. This could be any combination of a web client, a command line client, a mobile client - or embedded clients built into existing apps. It could even be a piece of hardware (e.g. a drone) that is Matrix enabled.
federation
Federation means that separate instances of a service communicate - the best example of this is email servers, in which it's possible to send mail between difference service providers. For Matrix, this means that data about rooms and message history is shared between servers of participating users.
Since events are extensible it is possible for malicious users and/or servers to add keys that are, for example offensive or illegal. Since some events cannot be simply deleted (e.g. membership events) we instead 'redact' events, essentially stripping the event of all keys that are not required by the protocol. Redacting an event cannot be undone, allowing server owners to also delete the offending content from the databases.
Currently, no. We are looking at options for decentralising or migrating user accounts between multiple servers, and might add this feature at a later stage.
Spaces are a collections of rooms. #community:matrix.org is the official matrix community space containing rooms managed by the core Matrix team.
Spaces are the replacements for the deprecated communities which were also known as groups. Other than groups a space itself is a Room.
community
Communities are collections of rooms. They have been replaced by spaces.
group
Groups are now known as communities, they are collections of rooms. They have been replaced by spaces.
space
Spaces are collections of rooms as rooms. They replace communites and groups.
sigil
Sigils refer the symbols uses at the beginning of many matrix identifiers. For example '@' is used for users, '#' for rooms, and '+' for communities.
For an introduction to the Matrix architecture, see https://matrix.org/docs/spec#architecture.
For a more thorough introduction see: https://matrix.org/docs/spec#room-structure.
A room is a conceptual place where users can send and receive events. Events are sent to a room, and all participants in that room with sufficient access will receive the event.
For example:
Is there any merit in a proposal that the current matrix.org Freenode bridge could be taken off matrix.org and put on a new HS (at a new server-name domain such as freenode.matrix.org) so as to not be bogged down in performance?
目前的 matrix.org Freenode 网桥可以从 matrix.org 上取下来并放在一个新的 HS 上(在一个新的服务器名称域,例如 freenode.matrix.org)以免陷入困境的提议有什么好处吗性能下降?
The Matrix.org Foundation currently runs one homeserver: matrix.org. This homeserver is operationally intensive and can sometimes suffer from slow response times. However running two homeservers would not improve performance, because the work done to maintain one homeserver would need to be duplicated. Also, the traffic on the bridge instance would be intensive just by itself. Running two intensive homeservers, where optimisations such as caching and federation traffic batching would need to be duplicated would have a marked decrease in overall performance.
Running the bridge on another homeserver means the same traffic will be hitting matrix.org, except it now has to be handled by the federation inbound workers too. Now you have two hosts handling the same amount of traffic. You might see a benefit to federated homeservers, but the new homeserver will struggle just as much with inbound/outbound federation slowness as it does now with bridging.
Further, it may turn out that the ongoing work on Synapse to introduce shared master processes actually makes it so much more efficient that whole benefit of creating two homeservers is now moot. Find out more about this work in this demo from Erik.
End-to-End encryption describes a scenario where a message is encrypted at the device or client of the sender, and is only decrypted by the device or client of the receiver, with no decryption or reading performed on the server.
End-to-End Encryption is fully supported in Matrix. New rooms have encryption enabled by default, and all existing rooms can optionally have End-to-End Encryption turned on.
End-to-end encryption is currently available in:
E2E is available in matrix-nio, a Client-Server library for Python.
All clients (and SDK/libs) can benefit from E2EE by using pantalaimon, which functions as a proxy daemon.
There is no value in encrypting public rooms. If anyone can join the room then encryption does not protect the contents, and may offer inconvenience for some users.
The Matrix Specification describes and prescribes the interaction between Application Services and more.
The spec is available to read on matrix.org.
To contribute to the development of the Matrix Specification, see https://matrix.org/docs/spec/proposals.
Client
Users in Matrix use one or more clients to communicate. This could be any combination of a web client, a command line client, a mobile client - or embedded clients built into existing apps. It could even be a piece of hardware (e.g. a drone) that is Matrix enabled.
homeserver
Each account in the Matrix federation is associated with a single homeserver. The software running at this server stores the history and account information for that user. Homeservers synchronise message history with other homeservers.
You can view the spec at https://matrix.org/docs/spec/.
To contribute to the Matrix Specification, first take a look at the documentation as it is currently written, then review the process for new proposals. You should start by writing a publicly-accessible proposal describing your change.
To see the proposals currently under discussion,join us in #matrix-spec:matrix.org.
See the documentation at https://matrix.org/docs/spec/proposals. In summary:
"MSC" refers to Matrix Spec Change, each proposal is assigned an MSC number to make referencing them easier.
MSC numbers are taken from GitHub issues on the matrix-doc repo. To see a list of all active MSCs, and to understand how to contribute your own, see https://matrix.org/docs/spec/proposals.
Voice (and video) over Matrix uses the WebRTC 1.0 standard to transfer call media (i.e. the actual voice and video traffic). Matrix is used to signal the establishment and termination of the call by sending call events, like any other event.
WebRTC encrypts the media that's being sent. The signalling events that set up (and end) the call are encrypted if the room they were sent in has enabled encryption.
VoIP calls should work if both parties are on public networks. However, in practice one (or both) devices are often behind NAT, and so having a TURN server is important to help set up the call.
See this guide for setting up a TURN server with Synapse.
Synapse is a Matrix "homeserver" implementation developed by the matrix.org core team, written in Python 3/Twisted. It is intended to showcase the concept of Matrix and let folks see the spec in the context of a codebase and let you run your own homeserver and generally help bootstrap the ecosystem.
homeserver
Each account in the Matrix federation is associated with a single homeserver. The software running at this server stores the history and account information for that user. Homeservers synchronise message history with other homeservers.
Take a look at the Synapse Installation Guide. There are options for installing using docker and/or ansible, plus manual installation instructions.
This is because both provide a mature and well known event-driven async IO framework for writing serverside code. Whilst this has been okay for our initial experimentation and proof of concept, it's future homeserver work will be written in a more strongly typed language (e.g. Go).
As of July 2018 work is progressing on Dendrite, a homeserver from the matrix.org core team written in Go.
homeserver
Each account in the Matrix federation is associated with a single homeserver. The software running at this server stores the history and account information for that user. Homeservers synchronise message history with other homeservers.
Synapse is very database dependent (as of Oct 2015; this is improving in the near future however), and we like having the flexibility to sculpt our own queries.
Federation in Matrix means that data is only shared between servers of participating users of a room. If all users in a room are on your server, no data is shared with other servers.
federation
Federation means that separate instances of a service communicate - the best example of this is email servers, in which it's possible to send mail between difference service providers. For Matrix, this means that data about rooms and message history is shared between servers of participating users.
Room state takes up a lot of space! To be specific, regular snapshots are taken of room states, so you can rapidly find out the state for historical events.
Why is it so important to record this, and to know the past room state including full member list?
It's needed to enable access control and state resolution, for example the homeserver needs to be able to decide:
Synapse stores these snapshots approximately every 100 messages, with deltas in between.
| Term | Definition |
|---|---|
| Client | Users in Matrix use one or more clients to communicate. This could be any combination of a web client, a command line client, a mobile client - or embedded clients built into existing apps. It could even be a piece of hardware (e.g. a drone) that is Matrix enabled. |
| matrixed together | In mathematics, a matrix is a lattice-like arrangement, in which expressions can be combined and treated as a single entity |
| homeserver | Each account in the Matrix federation is associated with a single homeserver. The software running at this server stores the history and account information for that user. Homeservers synchronise message history with other homeservers. |
| Synapse | Synapse is a homeserver implemented in Python by the matrix.org core team. It is currently by far the most installed homeserver available. |
| interoperable | A more general definition of interoperability is for systems to be able to freely exchange data with another by a known mechanism. In the case of matrix, we have openly documented how to communicate with our HTTP APIs. |
| New Vector | New Vector is a company formed to build Matrix.org. It is a continuation of the original project team, and is focused on development and maintenance of matrix.org. |
| federation | Federation means that separate instances of a service communicate - the best example of this is email servers, in which it's possible to send mail between difference service providers. For Matrix, this means that data about rooms and message history is shared between servers of participating users. |
| SIP | Session Initiation Protocol is a communications protocol for signaling and controlling multimedia communication sessions in applications of Internet telephony for voice and video calls. |
| XMPP | XMPP is a communication protocol for message-oriented middleware based on XML. We think of Matrix and XMPP as being quite different; at its core Matrix can be thought of as an eventually consistent global JSON database, whilst XMPP can be thought of as a message passing protocol. |
| RCS | Rich Communication Services is a communication protocol between mobile-telephone carriers and between phone and carrier, aiming at replacing SMS messages with a text-message system that is richer, provides phonebook polling (for service discovery), and transmit in-call multimedia. |
| bridging | Bridging to Matrix means that it's possible to read and write to channels hosted outside matrix. For example, it's possible to speak in IRC and slack rooms. |
| Element | Element is a popular matrix client developed by the core matrix.org team. It's available as a web app, on Android and on iOS. |
| client SDK | A client SDK makes it easier to develop client applications using matrix. See: How do I Matrix-enable my existing app? |
| MXID | Matrix user IDs (MXID) are unique user IDs. They are in the format @username:homeserver.tld. |
| 3PID | Third-party IDs (3PIDs) are IDs from other systems or contexts, such as email addresses, social network accounts and phone numbers. |
| the spec | The Matrix Specification describes the interactions between actors in the Matrix ecosystem, including Server-Server and Client-Server. You can see the spec here. |
| sigil | Sigils refer the symbols uses at the beginning of many matrix identifiers. For example '@' is used for users, '#' for rooms, and '+' for communities. |
| community | Communities are collections of rooms. They have been replaced by spaces. |
| group | Groups are now known as communities, they are collections of rooms. They have been replaced by spaces. |
| space | Spaces are collections of rooms as rooms. They replace communites and groups. |
| room | A room is a fundamental building bock of the matrix architecture: events are typically sent in the context of a room. A room is a conceptual place where users can send and receive events. Events are sent to a room, and all participants in that room with sufficient access will receive the event. See more detail. |
| bot | A bot is an autonomous agent. In the context of matrix, it means software which is able to make automated posts in rooms. |
| pubsub | The publish-subscribe pattern describes an architecture in which message senders push messages to a location, without needing to know who the subscribers will be. For Matrix, this means a client can send a message to a room without knowing the members, and the members can read that message. |
| Postgres | While Synapse can be installed using Sqlite, Postgres is preferred for any significant use. |
Brought to you by the creators of Matrix, who have been running the biggest homeserver in the network since 2014. Every homeserver comes with a custom instance of Element.
matrix.zerocarbon.shop
Service provided by ungleich.ch in their own datacenter in Linthal, Switzerland. They use an old building, second-hand servers, passive cooling and are directly plugged into an on-site hydroelectric power plant!
That service will create your Matrix Homeserver on your domain and server (doesn't matter if it's cloud provider or on an old laptop in the corner of your room), (optional) maintains it (server's system updates, cleanup, security adjustments, tuning, etc.; Matrix Homeserver updates & maintenance) and (optional) provide full-featured email service for your domain.
Matrix Space
Ossrox is a company from Germany dedicated to hosting open-source services. Not only has the company name been derived from the motto "Open-Source Software Rocks", but also their corporate culture. The three most important principles of the company are security, privacy and sustainability - thanks to open-source software. In addition to Matrix, Ossrox also provides many other solutions e.g. in the messaging, groupware and web meeting segments.










A Python 3.6+ asyncio Matrix framework.
Components:

µtrix is a client library for using the Matrix protocol in MicroPython, e.g. on ESP-based boards with
WiFi connectivity.
You can see in action in a video on the
Matrix door bell project at Hack'n'Sun 2021

nio is a multilayered matrix client library. The underlying base layer doesn't
do any IO on its own. On top of the base layer, a no-IO HTTP client
implementation exists, as well as a full fledged batteries included asyncio
layer using aiohttp.
The full API documentation for nio can be found at
https://matrix-nio.readthedocs.io
To install nio, simply use pip:
$ pip install matrix-nio
Note that this installs nio without end-to-end encryption support. For e2ee
support, python-olm is needed which requires the
libolm C library (version 3.x).
After libolm has been installed, the e2ee enabled version of nio can be
installed using pip:
$ pip install "matrix-nio[e2e]"
Unless special requirements disallow the usage of asyncio, by far the easiest
way to use nio is using the asyncio layer.
Please do note that these examples require python 3.5+ for the async/await
syntax. nio on the other hand works with older python versions as well.
import asyncio
from nio import AsyncClient
async def main():
client = AsyncClient("https://example.org", "@alice:example.org")
await client.login("hunter1")
await client.room_send(
room_id="!test:example.org",
message_type="m.room.message",
content={
"msgtype": "m.text",
"body": "Hello World"
}
)
await client.close()
asyncio.get_event_loop().run_until_complete(main())import asyncio
from nio import (AsyncClient, RoomMessageText)
async def message_cb(room, event):
print(
"Message received for room {} | {}: {}".format(
room.display_name, room.user_name(event.sender), event.body
)
)
async def main():
client = AsyncClient("https://example.org", "@alice:example.org")
client.add_event_callback(message_cb, RoomMessageText)
await client.login("hunter1")
await client.sync_forever(timeout=30000)
asyncio.get_event_loop().run_until_complete(main())The full API documentation for nio can be found at
https://matrix-nio.readthedocs.io

(Version 2.4.1)
Simple-Matrix-Bot-Lib is a Python bot library for the Matrix ecosystem built on matrix-nio.
View on Github or View on PyPi or
View docs on readthedocs.io
Learn how you can contribute here.
Installation from PyPi:
python -m pip install simplematrixbotlibDownload from github:
git clone --branch master https://github.com/KrazyKirby99999/simple-matrix-bot-lib.git# echo.py
# Example:
# randomuser - "!echo example string"
# echo_bot - "example string"
import simplematrixbotlib as botlib
creds = botlib.Creds("https://home.server", "echo_bot", "pass")
bot = botlib.Bot(creds)
PREFIX = '!'
@bot.listener.on_message_event
async def echo(room, message):
match = botlib.MessageMatch(room, message, bot, PREFIX)
if match.is_not_from_this_bot() and match.prefix() and match.command("echo"):
await bot.api.send_text_message(
room.room_id, " ".join(arg for arg in match.args())
)
bot.run()More information and examples can be found here.

Matrix.org's JS SDK.
Download the browser version from
https://github.com/matrix-org/matrix-js-sdk/releases/latest and add that as a
<script> to your page. There will be a global variable matrixcs
attached to window through which you can access the SDK. See below for how to
include libolm to enable end-to-end-encryption.
The browser bundle supports recent versions of browsers. Typically this is ES2015
or > 0.5%, last 2 versions, Firefox ESR, not dead if using
browserlists.
Please check the working browser example for more information.
Ensure you have the latest LTS version of Node.js installed.
This SDK targets Node 10 for compatibility, which translates to ES6. If you're using
a bundler like webpack you'll likely have to transpile dependencies, including this
SDK, to match your target browsers.
Using yarn instead of npm is recommended. Please see the Yarn install guide
if you do not have it already.
yarn add matrix-js-sdk
import * as sdk from "matrix-js-sdk";
const client = sdk.createClient("https://matrix.org");
client.publicRooms(function(err, data) {
console.log("Public Rooms: %s", JSON.stringify(data));
});See below for how to include libolm to enable end-to-end-encryption. Please check
the Node.js terminal app for a more complex example.
To start the client:
await client.startClient({initialSyncLimit: 10});You can perform a call to /sync to get the current state of the client:
client.once('sync', function(state, prevState, res) {
if(state === 'PREPARED') {
console.log("prepared");
} else {
console.log(state);
process.exit(1);
}
});To send a message:
const content = {
"body": "message text",
"msgtype": "m.text"
};
client.sendEvent("roomId", "m.room.message", content, "", (err, res) => {
console.log(err);
});To listen for message events:
client.on("Room.timeline", function(event, room, toStartOfTimeline) {
if (event.getType() !== "m.room.message") {
return; // only use messages
}
console.log(event.event.content.body);
});By default, the matrix-js-sdk client uses the MemoryStore to store events as they are received. For example to iterate through the currently stored timeline for a room:
Object.keys(client.store.rooms).forEach((roomId) => {
client.getRoom(roomId).timeline.forEach(t => {
console.log(t.event);
});
});
A Botkit connector for Matrix
$ npm install botkit-matrix
let config = {
'baseUrl': 'https://matrix.org',
'botUserId': '@youruserid:matrix.org',
'password': 'yourpassword',
'localStorage': 'filepath'
};
require('botkit-matrix').MatrixController(config)
.then((controller) => {
controller.hears(['hi', 'hello'], 'message_received', function (bot, message) {
bot.reply(message, "Hello, world!");
});
});You can get a sample bot at botkit-matrix-sample
For more features see Botkit Core
Small Matrix Little Bot
Very small implementation (bare essential) to quickly setup a Matrix Bot in Deno/Typescript/Web.
const client = new SmallBot({
accessToken: "mysecretaccesstoken",
homeserverUrl: "https://matrix.org/",
eventHandler: async (client, roomId, event) => {
if (event.sender !== client.ownUserId) {
await client.sendRoomNotice(roomId, "You said: <b>" + event.content.body + "</b>");
}
}
});
await client.start();You can find this modules on deno.land https://deno.land/x/smallbot_matrix

This library sits on top of the core application service library and provides an API for setting up bridges quickly.
Get it from GitHub and have a look at the HOW-TO for a step-by-step tutorial on setting up a new custom bridge!
Used by matrix-appservice-slack, matrix-bifröst, full native Gitter bridge, and others.
__________________________
| |
| Your bridge e.g. IRC |
|__________________________|
__|___________________|___
| |
| matrix-appservice-bridge |
|__________________________|
__|___________________|___
| |
| matrix-appservice |
| matrix-js-sdk |
|__________________________|
Bots on matrix often have very different requirements than regular clients or users. This SDK is aimed towards making bots more lightweight and responsive. Much of the library is a direct proxy to the client/server API, however it abstracts away the HTTP part as much as possible.
The source, and more information, can be found on GitHub.
This package can be found on npm:
npm install matrix-bot-sdkHere's an example of a very simple bot written using this library. It will auto-join rooms and respond to !hello as a command.
import {
MatrixClient,
SimpleFsStorageProvider,
AutojoinRoomsMixin,
RichReply,
} from "matrix-bot-sdk";
// where you would point a client to talk to a homeserver
const homeserverUrl = "https://matrix.org";
// see https://t2bot.io/docs/access_tokens
const accessToken = "YourSecretAccessToken";
// We'll want to make sure the bot doesn't have to do an initial sync every
// time it restarts, so we need to prepare a storage provider. Here we use
// a simple JSON database.
const storage = new SimpleFsStorageProvider("hello-bot.json");
// Now we can create the client and set it up to automatically join rooms.
const client = new MatrixClient(homeserverUrl, accessToken, storage);
AutojoinRoomsMixin.setupOnClient(client);
// We also want to make sure we can receive events - this is where we will
// handle our command.
client.on("room.message", handleCommand);
// Now that the client is all set up and the event handler is registered, start the
// client up. This will start it syncing.
client.start().then(() => console.log("Client started!"));
// This is our event handler for dealing with the `!hello` command.
async function handleCommand(roomId, event) {
// Don't handle events that don't have contents (they were probably redacted)
if (!event["content"]) return;
// Don't handle non-text events
if (event["content"]["msgtype"] !== "m.text") return;
// We never send `m.text` messages so this isn't required, however this is
// how you would filter out events sent by the bot itself.
if (event["sender"] === await client.getUserId()) return;
// Make sure that the event looks like a command we're expecting
const body = event["content"]["body"];
if (!body || !body.startsWith("!hello")) return;
// If we've reached this point, we can safely execute the command. We'll
// send a reply to the user's command saying "Hello World!".
const replyBody = "Hello World!"; // we don't have any special styling to do.
const reply = RichReply.createFor(roomId, event, replyBody, replyBody);
reply["msgtype"] = "m.notice";
client.sendMessage(roomId, reply);
}For more usage information see GitHub.

A Golang Matrix framework. Used by gomuks,
go-neb, mautrix-whatsapp
and others.
This project is based on matrix-org/gomatrix.
The original project is licensed under Apache 2.0.
In addition to the basic client API features the original project has, this framework also has:
This project contains modules that are licensed under Apache 2.0:
Official Golang Matrix client SDK
ruma-client is a bare-bones Matrix client library with
support for all of the r0.6.0 client-server API, but without any bookkeeping apart from storing
authentication data.
These crates (Rust parlance for packages) contain endpoint definitions for the various Matrix APIs.
They can be used both for clients (ruma-client, matrix-rust-sdk) as well as servers (Conduit,
Maelstrom).
ruma-client-api contains serializable types for the requests and responses for each endpoint in the Matrix client API specification.
ruma-appservice-api contains serializable types for the requests and responses for each endpoint in the Matrix appservice API specification.
ruma-federation-api contains serializable types for the requests and responses for endpoints in the Matrix server-server (federation) API specification.
As of the time of writing (15.05.2020), it is still very incomplete.
These crates are the foundation for the API crates above and other Matrix-related applications written in Rust.
ruma-api contains core types used to define the requests and responses for each endpoint in the various Matrix API specifications. These types can be shared by client and server code for all Matrix APIs.
ruma-identifiers contains types for user IDs, room IDs and other identifiers defined by the Matrix API specifications.
ruma-events contains serializable types for the events in the Matrix specification.
ruma-signatures contains implementations of cryptographic signing, hashing and verification algorithms defined by the Matrix specification.

A Ruby gem for easing the development of software that communicates with servers implementing the Matrix protocol.
There is a Matrix room for the discussion about usage and development at #ruby-matrix-sdk:kittenface.studio.
Live YARD documentation can be found at; http://aleol57.gitlab-pages.liu.se/ruby-matrix-sdk
# Raw API usage
require 'matrix_sdk'
api = MatrixSdk::Api.new 'https://matrix.org'
api.login user: 'example', password: 'notarealpass'
api.whoami?
# => {:user_id=>"@example:matrix.org"}
# It's possible to call arbitrary APIs as well
api.request :get, :federation_v1, '/version'
# => {:server=>{:version=>"0.28.1", :name=>"Synapse"}}# Client wrapper
require 'matrix_sdk'
client = MatrixSdk::Client.new 'https://example.com'
client.login 'username', 'notarealpass' #, no_sync: true
client.rooms.count
# => 5
hq = client.find_room '#matrix:matrix.org'
# => #<MatrixSdk::Room:00005592a1161528 @id="!cURbafjkfsMDVwdRDQ:matrix.org" @name="Matrix HQ" @topic="The Official Matrix HQ - please come chat here! | To support Matrix.org development: https://patreon.com/matrixdotorg | Try http://riot.im/app for a glossy web client | Looking for homeserver hosting? Check out https://upcloud.com/matrix!" @canonical_alias="#matrix:matrix.org" @aliases=["#matrix:jda.mn"] @join_rule=:public @guest_access=:can_join @event_history_limit=10>
hq.guest_access?
# => true
hq.send_text "This is an example message - don't actually do this ;)"
# => {:event_id=>"$123457890abcdef:matrix.org"}# Client wrapper
require 'matrix_sdk'
client = MatrixSdk::Client.new 'https://example.com'
client.api.access_token = 'thisisnotarealtoken'
# Doesn't automatically trigger a sync when setting the token directly
client.rooms.count
# => 0
client.sync
client.rooms.count
# => 5
The [Matrix] SDK for Android wraps the Matrix REST API calls in asynchronous Java methods and provides basic structures for storing and handling data.
It is an Android Studio (gradle) project containing the SDK module.
https://github.com/vector-im/riot-android is the sample app which uses this SDK.
The Matrix APIs are split into several categories (see [matrix api]).
Basic usage is:
To log in, use an instance of the login API client.
HomeServerConnectionConfig hsConfig = new HomeServerConnectionConfig.Builder()
.withHomeServerUri(Uri.parse("https://matrix.org"))
.build();
new LoginRestClient(hsConfig).loginWithUser(username, password, new SimpleApiCallback<Credentials>());If successful, the callback will provide the user credentials to use from then on.
The session represents one user's session with a particular home server. There can potentially be multiple sessions for handling multiple accounts.
MXSession session = new MXSession.Builder(hsConfig, new MXDataHandler(store, credentials), getApplicationContext())
.build();sets up a session for interacting with the home server.
The session gives access to the different APIs through the REST clients:
session.getEventsApiClient() for the events API
session.getProfileApiClient() for the profile API
session.getPresenceApiClient() for the presence API
session.getRoomsApiClient() for the rooms API
For the complete list of methods, please refer to the [Javadoc].
Example
Getting the list of members of a chat room would look something like this:
session.getRoomsApiClient().getRoomMembers(<roomId>, callback);The same session object should be used for each request. This may require use
of a singleton, see the Matrix singleton in the app module for an
example.
One important part of any Matrix-enabled app will be listening to the event stream, the live flow of events (messages, state changes, etc.).
This is done by using:
session.startEventStream();This starts the events thread and sets it to send events to a default listener.
It may be useful to use this in conjunction with an Android Service to
control whether the event stream is running in the background or not.
The data handler provides a layer to help manage data from the events stream. While it is possible to write an app with no
data handler and manually make API calls, using one is highly recommended for most uses. The data handler :
MXDataHandler dataHandler = new MXDataHandler(new MXMemoryStore());creates a data handler with the default in-memory storage implementation.
To be informed of events, the app needs to implement an event listener.
session.getDataHandler().addListener(eventListener);This listener should subclass MXEventListener and override the methods as needed:
onPresenceUpdate(event, user)
Triggered when a user's presence has been updated.
onLiveEvent(event, roomState)
Triggered when a live event has come down the event stream.
onBackEvent(event, roomState)
Triggered when an old event (from history), or back event, has been returned after a request for more history.
onInitialSyncComplete()
Triggered when the initial sync process has completed. The initial sync is the first call the event stream makes
to initialize the state of all known rooms, users, etc.
The Room object provides methods to interact with a room (getting message history, joining, etc).
Room room = session.getDataHandler().getRoom(roomId);gets (or creates) the room object associated with the given room ID.
The RoomState object represents the room's state at a certain point in time: its name, topic, visibility (public/private), members, etc.
onLiveEvent and onBackEvent callbacks (see Registering a listener) return the event, but also the state of the room at the time of the event to
serve as context for building the display (e.g. the user's display name at the time of their message). The state provided is the one before
processing the event, if the event happens to change the state of the room.
When entering a room, an app usually wants to display the last messages. This is done by calling
room.requestHistory();The events are then returned through the onBackEvent(event, roomState) callback in reverse order (most recent first).
This does not trigger all of the room's history to be returned but only about 15 messages. Calling requestHistory() again will then
retrieve the next (earlier) 15 or so, and so on. To start requesting history from the current live state (e.g. when opening or reopening a room),
room.initHistory();must be called prior to the history requests.
Matrix home servers provide a content API for the downloading and uploading of content (images, videos, files, etc.).
The content manager provides the wrapper around that API.
session.getContentManager();retrieves the content manager associated with the given session.
Content hosted by a home server is identified (in events, avatar URLs, etc.) by a URI with a mxc scheme (mxc://matrix.org/xxxx for example).
To obtain the underlying HTTP URI for retrieving the content, use
contentManager.getDownloadableUrl(contentUrl);where contentUrl is the mxc:// content URL.
For images, an additional method exists for returning thumbnails instead of full-sized images:
contentManager.getDownloadableThumbnailUrl(contentUrl, width, height, method);which allows you to request a specific width, height, and scale method (between scale and crop).
To upload content from a file, use
contentManager.uploadContent(filePath, callback);specifying the file path and a callback method which will return an object on completion containing the mxc-style URI where the uploaded
content can now be found.
See the sample app and Javadoc for more details.
Matrix client with the full support of the Client-Server API.
Core classes to write bots and appservice. (WIP)
Common classes used in all sdk and implementations. (WIP)
Core classes to write custom homeserver. (Empty)
Core classes to write custom identity server. (WIP)

A small and simple java API for the Matrix ClientServer Protocol (see clientServer api)
The API is still in Beta and known for bugs. If you found or missing a feature one you can create a new issue.
With credentials
//https not supported yet
Client c = new Client("http://matrix.your.server.xyz:8008");
c.login("examplebot", "wordpass123", loginData -> {
if (loginData.isSuccess()) {
//Do sth with the bot
} else {
System.err.println("error logging in");
}
});With Usertoken
//https not supported yet
Client c = new Client("http://matrix.your.server.xyz:8008");
c.login("Y0ur70ken", loginData -> {
if (loginData.isSuccess()) {
//Do sth with the bot
} else {
System.err.println("error logging in");
}
});For an examplebot you can have a look at my Grep Bot

This open-source library allows you to build iOS apps compatible with
Matrix (http://www.matrix.org), an open standard for interoperable
Instant Messaging and VoIP.
This SDK implements an interface to communicate with the Matrix
Client/Server API which is defined at
https://spec.matrix.org/latest/client-server-api/.
The SDK uses CocoaPods (http://cocoapods.org/) as library dependency
manager. In order to set this up:
sudo gem install cocoapods
pod setupThe best way to add the last release of the Matrix SDK to your
application project is to add the MatrixSDK dependency to your Podfile:
Obj-C: pod 'MatrixSDK'
Obj-C: pod 'MatrixSDK'
Swift: pod 'SwiftMatrixSDK'
Swift: pod 'SwiftMatrixSDK'
If you want to use the develop version of the SDK, use instead:
Obj-C pod: 'MatrixSDK', :git => 'https://github.com/matrix-org/matrix-ios-sdk.git', :branch => 'develop'
Obj-C pod: 'MatrixSDK', :git => 'https://github.com/matrix-org/matrix-ios-sdk.git', :branch => 'develop'
Swift pod: 'SwiftMatrixSDK', :git => 'https://github.com/matrix-org/matrix-ios-sdk.git', :branch => 'develop'
Swift pod: 'SwiftMatrixSDK', :git => 'https://github.com/matrix-org/matrix-ios-sdk.git', :branch => 'develop'
If you want to enable VoIP using the http://webrtc.org VoIP stack, add
the following pod to you app Podfile:
pod 'MatrixSDK/JingleCallStack'As a quick overview, there are the classes to know to use the SDK.
MXRestClient
: Exposes the Matrix Client-Server API as specified by the Matrix
standard to make requests to a homeserver.
These classes are higher level tools to handle responses from a
homeserver. They contain logic to maintain consistent chat room data.
MXSession
: This class handles all data arriving from the homeserver. It uses a
MXRestClient instance to fetch data from the homeserver, forwarding
it to MXRoom, MXRoomState, MXRoomMember and MXUser objects.
MXRoom
: This class provides methods to get room data and to interact with
the room (join, leave...).
MXRoomState
: This is the state of room at a certain point in time: its name,
topic, visibility (public/private), members, etc.
MXRoomMember
: Represents a member of a room.
MXUser
: This is a user known by the current user, outside of the context of
a room. MXSession exposes and maintains the list of MXUsers. It
provides the user id, displayname and the current presence state
The sample app (https://github.com/matrix-org/matrix-ios-console)
demonstrates how to build a chat app on top of Matrix. You can refer to
it, play with it, hack it to understand the full integration of the
Matrix SDK. This section comes back to the basics with sample codes for
basic use cases.
One file to import:
Obj-C:
#import <MatrixSDK/MatrixSDK.h>Swift:
import SwiftMatrixSDK
Quotient (former QMatrixClient) enables application development for Matrix using Qt. Its two main deliverables are libQuotient, the library to make applications that use Matrix, and Quaternion, the reference client using most of libQuotient. Main features for client development are there, with E2EE and support of full-fledged application services development in the roadmap.
Aside from Quaternion, Quotient code is used by Spectral and a few other clients.
The code, releases and issue trackers can be found in the project's GitHub organisation. Aside from the dedicated Matrix room (see above), news about libQuotient and Quaternion are regularly posted to This Week in Matrix.

libkazv is a sans-io C++ (gnu++17) client library, built upon lager. It supports end-to-end encryption.
Read the API documentation on its website.
Trixnity is a multiplatform Matrix SDK written in Kotlin.
You can write clients, bots, servers and appservices with it.
This SDK supports JVM/JS/Native as targets. Ktor is used for the HTTP client/server and
kotlinx.serialization for the serialization/deserialization.
Trixnity aims to be strongly typed, customizable and easy to use. You can register custom events and Trixnity will take
care, that you can send and receive that type.
A Matrix library for C# UWP.

A .NET standard 2.0 library supporting a subset of Matrix APIs including room management and basic message functions.
Can be used as a basis for more complicated SDKs.